+++ 2014-11-05: The new home of catch-exception code is https://github.com/Codearte/catch-exception Thank you, Mariusz! The googlecode project page won't be maintained any longer. +++

+++ 2014-05-02: Java 8's lambda expressions will make catch-exception redundant in the long term. +++

+++ 2013-11-06: Release 1.2.0 available in Maven Central, see Installation page +++

This library catches exceptions in a single line of code and makes them available for further analysis.

Usage

The most basic usage is: ``` import static com.googlecode.catchexception.CatchException.*;

// given: an empty list List myList = new ArrayList();

// when: we try to get the first element of the list // then: catch the exception if any is thrown catchException(myList).get(1);

// then: we expect an IndexOutOfBoundsException assert caughtException() instanceof IndexOutOfBoundsException; ```

The last both lines of code can be combined in a single line of code if you like:

verifyException(myList, IndexOutOfBoundsException.class).get(1);

More information about the usage you find in the Javadoc documentation.

BDD-like

If you prefer a BDD-like approach, you can use CatchExceptionBdd for another code style: ``` import static com.googlecode.catchexception.CatchException.; import static com.googlecode.catchexception.apis.CatchExceptionBdd.;

// given: an empty list List myList = new ArrayList();

// when: we try to get the first element of the list when(myList).get(1);

// then: we expect an IndexOutOfBoundsException then(caughtException()) .isInstanceOf(IndexOutOfBoundsException.class) .hasMessage("Index: 1, Size: 0") .hasNoCause(); ```

The assertions used here are part of Fest Assertions 2.0.

Alternatively, you can use CatchExceptionAssertJ with AssertJ assertions.

Hamcrest

If you prefer Hamcrest matchers to express assertions, you can use CatchExceptionHamcrestMatchers with the following code style: ``` import static com.googlecode.catchexception.CatchException.; import static com.googlecode.catchexception.apis.CatchExceptionHamcrestMatchers.;

// given: an empty list List myList = new ArrayList();

// when: we try to get the first element of the list catchException(myList).get(1);

// then: we expect an IndexOutOfBoundsException with message "Index: 1, Size: 0" assertThat(caughtException(), allOf( is(IndexOutOfBoundsException.class), hasMessage("Index: 1, Size: 0"), hasNoCause() ) ); ```

Catch constructor exceptions

Catch-exception does not provide an API to to catch exceptions that are thrown by constructors. Use try-catch-blocks instead. Alternatively, you can use the builder pattern if this makes sense anyway for your application:

``` import com.google.common.base.Supplier; // Google Guava

Supplier builder = new Supplier() { @Override public Thing get() { return new Thing("baddata"); } }; verifyException(builder).get(); ```

Thanks to the community for the example.

Catch throwables

If you want to catch both throwables and exceptions have a look at the catch-throwable packages. They provide the same API as the catch-exception packages but they belong to a different maven module.

JUnit4

If you want to handle expected exceptions, the documentation of catch-exception names some general reasons to prefer catch-exception in comparison to mechanisms that are provided by testing frameworks.

But some reasons that are specific to JUnit4 are outlined only here.

Collecting errors

If you want to combine the JUnit4's rules ExpectedException and ErrorCollector you will find out: this won't work.

Catch-exception instead can be easily combined with the error collecting rule:

``` @Rule public ErrorCollector collector = new ErrorCollector();

@Test public void testErrorCollectorWithExpectedException() {

// collect first error
collector.checkThat("a", equalTo("b"));

// collect second error
catchException(new ArrayList()).get(1);
collector.checkThat(caughtException(), is(IllegalArgumentException.class));

// collect third error
collector.checkThat(1, equalTo(2));

} ```

Theories respectively parameterized tests

Sometimes you want to test for an optional exception in a parameterized test. JUnit4's ExpectedException rule does not help in this case. This is another use case where catch-exception comes in quite handy.

Download

Go to the Installation page to get the latest release. This page provides also the Maven coordinates, prerequisites, and information about dependencies to other libraries.

Future enhancements

Nothing to do at the moment. There are no open issues and no open feature requests (last update: 10 Feb 2012).

Credits

Thanks to Szczepan Faber who made some suggestions about a BDD-like syntax for catch-exception. Finally, his ideas triggered the enhancements that came with the 1.0.4 release.

Questions, Suggestions, Issues

Questions and suggestions are welcome and can be sent to the discussion group. Issues can be reported on the Issues page of this project.

Please give me feedback of any kind. It is highly appreciated.